Selecting Media Handlers2

Media handler components are responsible for interpreting and manipulating a media's sample data. Each type of media has its own media handler, which deals with the specific characteristics of the media data. The Movie Toolbox provides a set of functions that allow you to gather information about a media handler and assign a particular media handler to a media. This section discusses those functions.

Each media handler has an associated data handler for each data reference. The data handler is responsible for fetching, storing, and caching the data that the media handler uses. The Movie Toolbox provides functions that allow you to get information about data handlers and to assign a particular data handler to a media.

The GetMediaHandler and GetMediaHandlerDescription functions allow you to retrieve information about a media handler.

You can use the SetMediaHandler function to assign a media handler to a media.

The GetMediaDataHandler and GetMediaDataHandlerDescription functions enable you to retrieve information about a data handler. Use the SetMediaDataHandler function to assign a data handler to a media.

GetMediaHandlerDescription

The GetMediaHandlerDescription function allows your application to retrieve information about a media handler. You specify the media.



 
pascal void GetMediaHandlerDescription (Media theMedia, 

                                         OSType *mediaType, 

                                         Str255 creatorName, 

                                         OSType *creatorManufacturer);

theMedia: Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).
mediaType: Contains a pointer to a field of data type OSType . The Movie Toolbox returns the media type identifier. This value indicates the type of media supported by this media handler. This value also corresponds to the component subtype specified for the media handler component. If you do not want to receive this information, set the mediaType parameter to nil . The following values are available:
creatorName: Points to a string. The Movie Toolbox returns the name of the media handler's creator. If you do not want to receive this information, set this parameter to nil .
creatorManufacturer: Contains a pointer to a long integer. The Movie Toolbox returns the 4-byte value that identifies the manufacturer of the component. If you do not want to retrieve this information, set this parameter to nil .

DESCRIPTION

The Movie Toolbox returns information about that media's media handler. This information describes the media handler that created the media, not the handler that is currently assigned to the media.

ERROR CODES

invalidMedia

-2008

This media is corrupted or invalid

GetMediaHandler

The GetMediaHandler function allows you to obtain a reference to a media handler component.

You can use this reference to call the media handler directly. See "Video Media Handler Functions," which begins on Video Media Handler Functions , and "Sound Media Handler Functions," which begins on Sound Media Handler Functions , for information about the functions that are supported by video and sound media handlers.



 
pascal MediaHandler GetMediaHandler (Media theMedia);

theMedia: Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).

DESCRIPTION

The GetMediaHandler function returns a reference to the media's media handler. If the function could not locate the media handler, it sets this reference to nil . You can use this reference to call the media handler.

ERROR CODES

invalidMedia

-2008

This media is corrupted or invalid

SetMediaHandler

The SetMediaHandler function allows you to assign a specific media handler to a track. The Movie Toolbox closes the track's previous media handler and then opens the new one. It is your responsibility to ensure that the media handler you specify can handle the data in the track.



 
pascal OSErr SetMediaHandler (Media theMedia,

                                         MediaHandlerComponent mH);

theMedia: Specifies the track for this operation. Your application obtains this track identifier from such Movie Toolbox functions as NewMovieTrack and GetMovieTrack (described on NewMovieTrack and GetMovieTrack , respectively).
mH: Contains a reference to a media handler component. You obtain this reference from the GetMediaHandler function, which is described in the previous section.

Note
Your application should not need to call the SetMediaHandler function. The Movie Toolbox assigns a media handler to each track when you load a movie.

ERROR CODES

invalidHandler

-2013

This handler is invalid

GetMediaDataHandlerDescription

The GetMediaDataHandlerDescription function allows your application to retrieve information about a media's data handler. You specify the media.



 
pascal void GetMediaDataHandlerDescription (Media theMedia, 

                                         short index, OSType *dhType, 

                                         Str255 creatorName, 

                                         OSType *creatorManufacturer);

theMedia: Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).
index: Identifies the data reference. You provide the index value that corresponds to the data reference for which you want to retrieve the data handler description. You must set this parameter to 1.
dhType: Contains a pointer to a field of data type OSType . The Movie Toolbox returns the data handler type identifier. This value indicates the type of data reference supported by this data handler. This value also corresponds to the component subtype specified for the data handler component. All QuickTime data references have a type value of 'alis' . If you do not want to receive this information, set the dhType parameter to nil .
creatorName: Points to a string. The Movie Toolbox returns the name of the data handler's creator. If you do not want to receive this information, set this parameter to nil .
creatorManufacturer: Contains a pointer to a long integer. The Movie Toolbox returns the 4-byte value that identifies the manufacturer of the component. If you do not want to retrieve this information, set this parameter to nil .

DESCRIPTION

The Movie Toolbox returns information about that media's data handler. This information describes the data handler that created the media data, not the handler that is currently assigned to the media.

ERROR CODES

invalidMedia

-2008

This media is corrupted or invalid

GetMediaDataHandler

The GetMediaDataHandler function allows you to determine a media's data handler.



 
pascal DataHandler GetMediaDataHandler (Media theMedia, 

                                         short index);

theMedia: Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).
index: Identifies the data reference. You provide the index value that corresponds to the data reference for which you want to retrieve the data handler. You must set this parameter to 1.

DESCRIPTION

The GetMediaDataHandler function returns a data handler identifier. This identifier is a component instance that specifies a connection to a data handler component (see the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for more information about components). If the Movie Toolbox cannot determine the data handler for the media you specify, the function sets this returned value to nil .

Note
Your application should not need to call this function.

ERROR CODES

invalidMedia

-2008

This media is corrupted or invalid

SetMediaDataHandler

The SetMediaDataHandler function allows you to assign a data handler to a media.



 
pascal OSErr SetMediaDataHandler (Media theMedia, short index, 

                                         DataHandlerComponent dataHandler);

theMedia: Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on NewTrackMedia and GetTrackMedia , respectively).
index: Identifies the data reference for this data handler. You provide the index value that corresponds to the data reference. You must set this parameter to 1.
dataHandler: Specifies the data handler for the media. This identifier is a component instance that specifies a connection to a data handler component (see the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for more information about components). If the data handler you specify cannot work with the data stored in the media, the function does not change the media's data handler.

DESCRIPTION

When you create a new media or load an existing media into memory, the media handler assigns an appropriate data handler to the track's media.

Note
Your application should not call the SetMediaDataHandler function. The Movie Toolbox assigns a data handler to each media when you load a movie.

ERROR CODES

badComponentType	-2005	Component cannot accommodate this data
invalidMedia	-2008	This media is corrupted or invalid